home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr44 / pctim12.zip / PCTIMER.DOC < prev    next >
Text File  |  1995-01-29  |  9KB  |  206 lines
  1. --------------------------- PCTIMER 1.2 --------------------------
  2. Program written by: Chih-Hao Tsai (c-tsai4@uiuc.edu)       1/29/95
  3. ------------------------------------------------------------------
  4. This  program  is  FREE. Feel free to use, re-distribute or modify
  5. it.  However, you should recognize that this program comes without
  6. any  warranty.  It  is  recommended that you examine and test this
  7. program  before  actually use it. If you find this program useful,
  8. or if you find a bug, please send an e-mail to me to let me know.
  9. ------------------------------------------------------------------
  10.  
  11. 1. PCTIMER
  12.  
  13.    PCTIMER  is  a  high-resolution timing routine in the form of C
  14.    functions. You can compile and link PCTIMER to your programs in
  15.    which millisecond (or even higher) accuracy timing is required.
  16.  
  17.    History
  18.  
  19.    11/5/94 Version 1.0
  20.  
  21.    The  first  freeware  release of PCTIMER. With source codes for
  22.    GNU C/C++ and Microsoft C/C++ compilers.
  23.  
  24.    1/16/95 Version 1.1
  25.  
  26.    (1)  In  version  1.0, gccint8.c only intercepts protected mode
  27.    int  8h,  which may cause loss of ticks when programs switch to
  28.    real  mode.  I  revised  gccint8.c that it would intercept both
  29.    protected mode and real mode int8h's. (I would like to thank DJ
  30.    Delorie,  Eli  Zaretskii,  and  Long  Doan  for  their  helpful
  31.    suggestions and discussions.)
  32.  
  33.    (2) I added sources for Turbo C/C++ compiler.
  34.  
  35.    (3) The delay8h function had been slightly modified.
  36.  
  37.    1/29/95 Version 1.2
  38.  
  39.    Revision  (and  correction)  of  gccint8.c. PCTIMER for GCC was
  40.    first  developed  under  gcc  2.6.0,  and it was found that the
  41.    following  instructions:  "r.x.cs  = rm_old_handler.rm_segment;
  42.    r.x.ip   =  rm_old_handler.rm_offset;  r.x.ss  =  r.x.sp  =  0;
  43.    _go32_dpmi_simulate_fcall_iret(&r);"     could     not     call
  44.    rm_old_handler.rm_segment:rm_old_handler.rm_offset   correctly.
  45.    Therefore,  my  solution  in PCTIMER 1.1 was to call f000:fea5,
  46.    which  is  the  default  handler  of int 8h in IBM PC and fully
  47.    compatible  BIOSes.  Since the bug has been fixed in gcc 2.6.3,
  48.    the  real  mode interrupt handler "rm_new8h" in gccint8.c could
  49.    now  be  revised. As a result, PCTIMER for GCC now requires GCC
  50.    version 2.6.3 or higher.
  51.  
  52. 2. RATIONALE FOR WRITING AND USING PCTIMER
  53.  
  54.    Although  the  timing  routines  of  most programming languages
  55.    always  report times to centisecond, the resolution of standard
  56.    timer  of  IBM-PCs is actually only 1/18.2 seconds. That is, if
  57.    you   use   the   standard  timing  routine  provided  by  your
  58.    programming  language,  the  precision  of  your measurement is
  59.    actually  55  milliseconds  with  a  plus/minus 27.5 seconds of
  60.    measurement  error!  I  wrote  PCTIMER  to provide IBM-PCs with
  61.    high-resolution timing ability.
  62.  
  63. 3. FEATURES
  64.  
  65.    (1) Precise: Basically, PCTIMER is designed to provide a timing
  66.    routine  with millisecond resolution. If such a resolution does
  67.    not  satisfy  you,  you  can  also  modify  it  to  get  higher
  68.    resolutions.  However, in most cases, millisecond resolution is
  69.    precise enough.
  70.  
  71.    (2)  Stable:  PCTIMER  sets  new  parameters  to  the  8254  IC
  72.    (Programmable  Interrupt  Timer)  to  get  high  frequencies of
  73.    SYSTEM  TIMER  Interrupt (IRQ0, or INT8h) whose default is 18.2
  74.    times  per  second.  However,  many hardware routines depend on
  75.    IRQ0.  Abnormal IRQ0 frequencies may cause the system unstable.
  76.    To  maintain  the  PC's stability, PCTIMER intercepts the INT8,
  77.    only calls the original INT8 at the frequency of 18.2 times per
  78.    second.   Consequently,   high-resolution   timing  and  system
  79.    stability are simultaneously achieved.
  80.  
  81.    (3)  Flexible:  Originally  I  wrote  PCTIMER to do millisecond
  82.    resolution  timing.  If millisecond precision in unnecessary to
  83.    you,  you  can  also  set  PCTIMER  to  do  centisecond timing.
  84.    Resolution  higher  than  millisecond is also possible, but you
  85.    have  to  modify  a  few  parts  of the program by yourself. It
  86.    should be an easy task.
  87.  
  88.    (4) Portable: Most public-domain timing routines are written in
  89.    assembly  codes, or in C codes with in-line assembly codes. The
  90.    assembly  codes  make those routine difficult to understand and
  91.    use  if  one  does  not  have  good  background of the assembly
  92.    language.  And  the  format of in-line assembly varies from one
  93.    compiler  to  another. Worst of all, several C compilers do not
  94.    support in-line assembly. PCTIMER does not have these problems,
  95.    because  all  functions  are  written  in C codes. There are no
  96.    assembly codes at all.
  97.  
  98. 4. SYSTEM AND COMPILER REQUIREMENTS
  99.  
  100.    (1)  PCTIMER  is  a  tiny  timing  routine  that  does not have
  101.    specific memory and CPU speed limitations. The only requirement
  102.    is  that  it  only  runs on IBM-AT compatible PCs. An XT is not
  103.    appropriate  because  an  XT  does not have an CMOS IC. PCTIMER
  104.    need the CMOS IC to obtain correct system time.
  105.  
  106.    (2)  PCTIMER  comes with three versions, one for GNU C/C++, one
  107.    for  Microsoft  C/C++, and one for Turbo C/C++. The GCC version
  108.    was  developed  under  GCC 2.6.3, the MSC version was developed
  109.    under  MSC  6.0,  and  the  Turbo C version was developed under
  110.    Turbo C/C++ 2.0. There should be no problems if you are using a
  111.    different  version  of  Turbo C or MSC. However, the version of
  112.    GCC *does* matter. Please do not use GCC older than 2.6.3.
  113.  
  114. 5. USING PCTIMER
  115.  
  116.    (1)  At  the beginning of your program, include the header file
  117.    of PCTIMER:
  118.  
  119.        #include "gccint8.h"
  120.  
  121.        /* "mscint8.h" for MSC; "tcint8.h" for Turbo C */
  122.  
  123.    (2)  Declare  three  unsigned  long  integers (of course, their
  124.    names are arbitrary):
  125.  
  126.        unsigned long int tick_1, tick_2, elapsedtime;
  127.  
  128.    (3)  In  your program, use the following function and parameter
  129.    to initiate the timer:
  130.  
  131.        init8h(1000); /* init8h(100) for centisecond resolution */
  132.        ticks_8h = 0;
  133.  
  134.    (4) Timing
  135.  
  136.        tick_1 = ticks_8h;
  137.        /* .... do some stuff here .... */
  138.        tick_2 = ticks_8h;
  139.        elapsedtime = time8h(tick_1, tick_2);
  140.  
  141.        /*  The  function  "time8h" always returns millisecond unit
  142.        digits.  That  is,  if you use init8h(1000), then the value
  143.        returned  by  time8h  is  exactly  the time elapsed between
  144.        tick_1  and  tick_2.  However,  if you use init8h(100), the
  145.        value   returned   by  time8h  is  still  in  the  unit  of
  146.        millisecond.  The  difference is that the value returned by
  147.        time8h  in  the  init8h(1000)  condition is measured in the
  148.        precision  of  one millisecond, while the value returned by
  149.        time8h  in  the  init8h(100)  condition  is measured in the
  150.        precision of 10 milliseconds. */
  151.  
  152.    (5) How to turn off the timer:
  153.  
  154.        quit8h();
  155.  
  156.        /*  Be  sure  to  turn  off  the  timer before your program
  157.        terminates.  Also  turn  off the timer before you set a new
  158.        parameter for init8h. */
  159.  
  160.    (6) delay8h and sound8h
  161.  
  162.        /*  The  "delay8h" is a high-resolution delay function. The
  163.        parameter  is  always in the unit of millisecond, no matter
  164.        what you put in the "init8h". However, the precision of the
  165.        delay  duration  depends on the parameter of "init8h". Here
  166.        is an example for a 150 milliseconds delay: */
  167.  
  168.        delay8h(150);
  169.  
  170.        /* the "sound8h" takes advantage of "delay8h" to generate a
  171.        sound  with  a  specific duration. Here is an example for a
  172.        800 Hz sound with 200 ms duration: */
  173.  
  174.        sound(800, 200);
  175.  
  176. 6. LIMITATION
  177.  
  178.    PCTIMER  uses  an unsigned long integer to count the cumulative
  179.    frequency  of  INT8h interrupts. Assuming you set init8h(1000),
  180.    ticks_8h  =  0, PCTIMER will work 4294967296/1000 = 4294967.296
  181.    seconds,  or  1193.05 hours without encountering the problem of
  182.    overflow. I hope that the 1193.05 hours would be pretty enough.
  183.    If  you do need to continuously use PCTIMER for a period longer
  184.    than  1193.05  hours,  just  reset  the  ticks_8h  to  zero  at
  185.    appropriate location of your program.
  186.  
  187. 7. FILES
  188.  
  189.     pctimer.doc    This file
  190.     gccint8.h      PCTIMER: Header file for GCC
  191.     gccint8.c      PCTIMER: Source code for GCC
  192.     mscint8.h      PCTIMER: Header file for Microsoft C
  193.     mscint8.c      PCTIMER: Source code for Microsoft C
  194.      tcint8.h      PCTIMER: Header file for Turbo C
  195.      tcint8.c      PCTIMER: Source code for Turbo C
  196.       test8.c      Source code for test8.exe
  197.       test8.exe    Test program (Note 1)
  198.    maketest.bat    Simple batch file to create test8.exe (Note 2)
  199.  
  200.    Note  1.  This test program was compiled by GCC 2.6.3. That is,
  201.    it requires PCs with 32-bit CPUs and go32.exe.
  202.  
  203.    Note  2. This batch file is also for GCC. Please make necessary
  204.    changes if you do not use GCC.
  205. ------------------------------------------------------------------
  206.